18 Star 118 Fork 38

嗝嗝 / TP5.1 Restful Api

加入 Gitee
与超过 1200万 开发者一起发现、参与优秀开源项目,私有仓库也完全免费 :)
免费加入
克隆/下载
贡献代码
同步代码
取消
提示: 由于 Git 不支持空文件夾,创建文件夹后会生成空的 .keep 文件
Loading...
README
Apache-2.0

TP5.1 Restful Api

PHP Version License star fork

介绍

PHP7.2 + TP5.1 + Restful Api ,构建的API项目架构,支持API文档输出、API接口自检、开启API JWT模式、反射路由模式、API参数自检等功能

为了本项目拥有更加直白与客观的简易性、阅读性、实用性,所用的扩展和第三方代码,均未考虑高度抽象和深度封装,各位大大可以很简单的看懂源码和框架设计。

如果有需要或涉及到高并发的服务架构,可以在issues提出,或者留言也行,我将参考大家的意愿,出一个版本或demo。

软件架构

软件架构说明

www  WEB部署目录(或者子目录)
├─application           应用目录
│  ├─api        接口模块目录(可以更改,但不建议:很麻烦,模块里面不建议写模型和视图)
│  │  ├─common.php      模块函数文件(接口函数推荐写在这里)
│  │  ├─controller      控制器目录
│  │  │  ├─v1          接口版本模块
│  │  │  ├─v...          接口版本模块
│  ├─common             公共模块目录(可以更改)
│  │
│  ├─command.php        命令行定义文件
│  ├─common.php         公共函数文件
│  └─provider.php       应用容器绑定定义
│  └─tags.php           应用行为扩展定义文件

├─config                应用配置目录
│  ├─api               模块配置目录
│  │  ├─app.php       应用配置
│  │
│  ├─api.php            接口配置
│  ├─app.php            应用配置
│  ├─cache.php          缓存配置
│  ├─cookie.php         Cookie配置
│  ├─database.php       数据库配置
│  ├─log.php            日志配置
│  ├─session.php        Session配置
│  ├─template.php       模板引擎配置
│  └─trace.php          Trace配置

├─route                 路由定义目录
│  ├─route.php          路由定义
│  └─...                更多

├─public                WEB目录(对外访问目录)
│  ├─index.php          入口文件
│  ├─router.php         快速测试文件
│  └─.htaccess          用于apache的重写

├─thinkphp              框架系统目录
│  ├─lang               语言文件目录
│  ├─library            框架类库目录
│  │  ├─think           Think类库包目录
│  │  └─traits          系统Trait目录
│  │
│  ├─tpl                系统模板目录
│  ├─base.php           基础定义文件
│  ├─console.php        控制台入口文件
│  ├─convention.php     框架惯例配置文件
│  ├─helper.php         助手函数文件
│  ├─phpunit.xml        phpunit配置文件
│  └─start.php          框架入口文件

├─extend                扩展类库目录
├─runtime               应用的运行时目录(可写,可定制)
├─vendor                第三方类库目录(Composer依赖库)
├─build.php             自动生成定义文件(参考)
├─composer.json         composer 定义文件
├─LICENSE.txt           授权说明文件
├─README.md             README 文件
├─think                 命令行入口文件

安装教程

  1. 克隆本项目代码
git clone https://gitee.com/china_wangyu/TP5.1-Restful-Api.git
  1. 进入项目工程
cd TP5.1-Restful-Api
  1. 使用composer更新项目扩展,提升项目安全性、可用性

推荐使用composer中国镜像源,具体操作见【文档

composer install

使用说明

必须配置以下内容

  1. 配置api.phpapp.php

api.php 目录在 {项目}/config/api.php

app.php 目录在 {项目}/config/api/app.php

  1. 配置route.php

route.php 目录在 {项目}/route/api.php

如果不修改模块,请直接使用默认配置

开启JWT模式 (可选)

  1. 配置api.php

    // 是否开启授权验证
    'API_AUTHORIZATION' => true,
  2. 修改Base.php项目基类(不建议修改)

    <?php
    /**
     * Created by User: wene<china_wangyu@aliyun.com> Date: 2019/4/3 Time: 16:36
     */
    
    namespace app\api\controller\v1;
    
    use think\restful\jwt\Jwt;
    
    /**
     * Class Reflex API基类
     * @package app\api\controller\v1
     */
    class Base extends \think\restful\Api
    {
        /**
         * Base constructor. 有什么事要在父类执行之后执行的代码,请写在parent::__construct($debug);下
         * @param bool $debug
         */
        public function __construct($debug = false)
        {
            parent::__construct($debug);
        }
    
        /**
         * 继承父类方法,如果有什么要在最开始执行的,请写在里面
         */
        protected function handle()
        {
            if ($this->config['API_AUTHORIZATION']){
                // 开启JWT验证,执行业务代码
                if(!isset($this->param['jwt']) or !isset($this->param['signature'])) {
                    // 没有jwt参数 或 signature 签名
                    $this->error('400 缺少API授权信息~');
                }
                $jwtArr = Jwt::decode($this->param['jwt'],$this->config['API_AUTHORIZATION_KEY']);
                $userJwtSignature = md5(join(',',$jwtArr['data']));
                if ($userJwtSignature !== $this->param['signature']) {
                    $this->error('400 API授权信息错误~');
                }
            }
        }
    }
  3. 修改token.php(不建议修改)

    <?php
    /**
     * Created by User: wene<china_wangyu@aliyun.com> Date: 2019/4/3 Time: 17:34
     */
    
    namespace app\api\controller;
    
    use think\Request;
    use think\restful\Base;
    use think\restful\jwt\Jwt;
    use think\restful\response\Json;
    class Token extends Base
    {
        public function __construct()
        {
            parent::__construct();
        }
    
        public function create()
        {
            $param = $this->param;
            if(empty($param['userName']) or empty($param['userLoginKey'])){
               return Json::json(404,'参数userName/userLoginKey不能为空~');
            }
            $token = $tokenTemplate = $this->config['API_AUTHORIZATION_TOKEN'];
            $token['iat'] = time();
            $token['nbf'] = $token['iat']  + 10;
            $token['exp'] = $token['iat'] + 600;
            $token['data'] = ['userName'=>$param['userName'],
                'userLoginKey'=>$param['userLoginKey']];
            $jwt = Jwt::encode($token,$this->config['API_AUTHORIZATION_KEY']);
            return Json::json(200,'操作成功~',[
                'jwt'=>$jwt,
                'tt'=>  $token['iat'],
                'exp' => $token['exp'],
                'signature' => md5(join(',',$token['data']))
            ]);
        }
    
        /**
         * 刷新时长
         * @return array
         */
        public function reset(){
            $param = $this->param;
            if(empty($param['jwt']))return Json::json(404,'参数jwt不能为空~');
            $jwtArr = Jwt::reset($jwt,$this->config['API_AUTHORIZATION_KEY']);
            return Json::json(200,'操作成功~',[
                'jwt'=> $jwtArr['jwt'],
                'tt'=>  $jwtArr['jwt']['iat'],
                'exp' => $jwtArr['jwt']['exp'],
                'signature' => md5(join(',',$jwtArr['token']['data']))
            ]);
        }
    }
    

API接口编码模板

  • auth文件举例

    代码模板

    <?php
    
    namespace app\api\controller\v1;
    
    /**
     * Class Auth Auth授权类
     * @package app\api\controller\v1
     */
    class Auth extends Base
    {
    
        /**
        * @doc 获取服务器授权1
        * @route /api/v1/auth get
        * @param string $appSecret 授权字符 require|alphaNum 1
        * @param string $appSec2t 授权字符1 require|alphaNum 1
        * @param string $appId 开发者ID
        * @success {"code":400,"msg":"appSecret不能为空","data":[]}
        * @error {"code":400,"msg":"appSecret不能为空","data":[]}
        */
        public function read()
        {
            return $this->success('成功~');
        }
    }

    接口类注释说明

    /**
     * Class Auth Auth授权类
     * @package app\api\controller\v1
     */
    class Auth extends Base

    接口方法注释

    /**
     * @doc 获取服务器授权1
     * @route /api/v1/auth get
     * @param string $appSecret 授权字符 require|alphaNum 1
     * @param string $appSec2t 授权字符1 require|alphaNum 1
     * @param string $appId 开发者ID
     * @success {"code":400,"msg":"appSecret不能为空","data":[]}
     * @error {"code":400,"msg":"appSecret不能为空","data":[]}
     */
    public function read()
    {
        return $this->success('成功~');
    }

    接口方法注释参数说明

    @ 名称 参数1注解 参数2注解 参数3注解
    doc API接口文档
    route API路由规则 请求类型
    param api参数 验证规则 默认值
    success API请求成功返回json示例
    error API请求失败返回json示例

接受接口请求数据

  • url 请求样例
http://127.0.0.1:8000/api/v1/auth?appSecret=12&appSec2t=12
  • 代码样例
public function read()
{
    # $this->param 就是接口请求数据,包含请求版本号,请求接口类名称
    return $this->success('成功~',$this->param);
}
  • 返回样例
{
"responseCode": 200,
"responseMsg": "成功~",
"responseData": {
    "appSecret": "12",
    "appSec2t": "12",
    "version": "v1",
    "controller": "auth"
    }
}

返回json数据

注意本函数与 TP 内置 think\Controllersuccess\errror同名

  • 状态为200的 样例

    public function read()
    {
        return $this->success('成功~');
    }
    {
    "responseCode": 200,
    "responseMsg": "成功~",
    "responseData": {
        "appSecret": "12",
        "appSec2t": "12",
        "version": "v1",
        "controller": "auth"
        }
    }
  • 状态为400的 样例

    public function read()
    {
        return $this->error('成功~');
    }
    {
    "responseCode": 400,
    "responseMsg": "参数错误:appSecret不能为空",
    "responseData": []
    }
  • success/error函数参数说明

    参数名称 注解 类型 默认值
    msg 接口调用提示
    data 返回数据 请求类型

输出API文档

  1. 需要设置api.phpAPI_AUTHORIZATION值为false

    // 是否开启授权验证
    'API_AUTHORIZATION' => false,
  2. 打开cmd/ssh工具

  3. 进入项目目录

  4. 执行命令

    C:\Users\zhns_\Desktop\php\TP5.1-Restful-Api [master ≡ +2 ~223 -1 !]
    >  php think api:make
    API markdown 接口文档地址: C:\Users\zhns_\Desktop\php\TP5.1-Restful-Api\\API接口文档2019-04-16 15.md
自检API接口
  1. 需要设置api.phpAPI_AUTHORIZATION值为false

    // 是否开启授权验证
    'API_AUTHORIZATION' => false,
  2. 打开cmd/ssh工具

  3. 进入项目目录

  4. 开启接口服务

    • 使用PHP内置服务器
    php -S {IP地址}:{端口} -t {项目目录}/public/
    • TP5 启动服务
    > php think run -H {IP地址} -P {端口}
    
    ThinkPHP Development server is started On <http://127.0.0.1:8000/>
    You can exit with `CTRL-C`
    Document root is: E:\VirtualBox\vms\CICD\labs\tp5restfulapi_architecture\public
  5. 然后配置项目 api.php 配置文件的参数 (可选)

'API_HOST'=> 'http://127.0.0.1:8000',# 设置API网址

如果没有配置这个,请在执行的时候加上-H指定网址

  1. 输入自检命令 php think API -C 1

    • 基本命令
    C:\Users\zhns_\Desktop\php\TP5.1-Restful-Api [master ≡ +2 ~223 -1 !]
    >  php think api:check
    API markdown 自检文档地址: C:\Users\zhns_\Desktop\php\TP5.1-Restful-Api\\API自检文档2019-04-16 15.md
    • 指定网址 php think API -C 1 -H
    C:\Users\zhns_\Desktop\php\TP5.1-Restful-Api [master ≡ +2 ~223 -1 !]
    >  php think api:check -H http://127.0.0.1:8000
    API markdown 自检文档地址: C:\Users\zhns_\Desktop\php\TP5.1-Restful-Api\\API自检文档2019-04-16 16.md

接口文档样例

详情请点击 【接口示例文档.md】查看效果。

本来想写成json格式的,后面想想还是这个makdown文档最为方便,希望大家喜欢。

项目自评

本扩展或者说是一个TP5.1+PHP7.2的后端项目API架构, 主要是帮助刚刚入行或者快速建站的朋友们,进行项目快速迭代开发, 把接口授权、接口验证、参数校验、接口文档输出、接口自验包裹封装起来, 只为大家用的安心。

帮助作者

项目开发或者扩展开发,都需要不断地编码尝试与线上环境验证。 所需的资源和时间都是有成本的,如果项目帮助到您了, 如果您有心帮助作者,请点击下方的捐赠按钮

参与贡献

  1. Fork 本仓库
  2. 新建 ts_{用户名} 分支
  3. 提交代码
  4. 新建 Pull Request

联系作者

ThinkPHP遵循Apache2开源协议发布,并提供免费使用。 版权所有Copyright © 2006-2018 by ThinkPHP (http://thinkphp.cn) All rights reserved。 ThinkPHP® 商标和著作权所有者为上海顶想信息科技有限公司。 Apache Licence是著名的非盈利开源组织Apache采用的协议。 该协议和BSD类似,鼓励代码共享和尊重原作者的著作权, 允许代码修改,再作为开源或商业软件发布。需要满足 的条件: 1. 需要给代码的用户一份Apache Licence ; 2. 如果你修改了代码,需要在被修改的文件中说明; 3. 在延伸的代码中(修改和有源代码衍生的代码中)需要 带有原来代码中的协议,商标,专利声明和其他原来作者规 定需要包含的说明; 4. 如果再发布的产品中包含一个Notice文件,则在Notice文 件中需要带有本协议内容。你可以在Notice中增加自己的 许可,但不可以表现为对Apache Licence构成更改。 具体的协议参考:http://www.apache.org/licenses/LICENSE-2.0 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

简介

TP5.1-Restful-Api 有全新版本了,更名为:TRR (ThinkPHP51 Reflection Restful API简写),更为简单、优雅、易上手,详情请点击后方链接: 展开 收起
PHP 等 3 种语言
Apache-2.0
取消

发行版

暂无发行版

贡献者

全部

近期动态

加载更多
不能加载更多了
PHP
1
https://gitee.com/china_wangyu/TP5.1-Restful-Api.git
git@gitee.com:china_wangyu/TP5.1-Restful-Api.git
china_wangyu
TP5.1-Restful-Api
TP5.1 Restful Api
master

搜索帮助